Incorporating the Library into Your Own Application
Customizing the Error Library
User System Requirements
Developer System Requirements
Version History
Introduction
The files in this folder represent the error database contained in Black & Bleu™, our commercial error analysis application. Using the information found in this folder, you can incorporate the most comprehensive Mac OS error list ever compiled into your own application. This document describes version 3.0 of the runtime library. V3.0 is the first public release of this offering.
The library database consists of 5,045 error codes, Apple's pneumonic name for each, the technology associated with each error code (such as QuickTime, AppleScript, Memory Manager, etc.) and Apple's short description of what the error means.
The BleuRoseErrorLib file is a hybrid Shared Library file. That means it is compatible with both PowerPC native applications as well as classic 68k code. This single library can be linked to your application whether it is Classic 68k, PowerPC Native or FAT. A context switch is not required when the library is called since the library is smart enough to activate the proper code for the mode you are currently in (68k or PPC).
This concept was first described by Joe Zobkiw in his book "A Fragment of Your Imagination", 1995, Addison Wesley, ISBN #0-201-48358-0.
Note: Neither Native Mac OS X support (Cocoa) nor Carbon support is not provided in this release. If you are interested in either of these technologies, let us know. Unless there is some interest expressed in Carbon and Cocoa support, we don't plan on providing it.
Files in this kit
Read about BleuRoseErrorLib The file you are currently reading
BleuRoseErrorLib See "Incorporating the Library ..." below
BleuRoseErrorLib License Print, sign and mail this document
Populate The Library See "Completing the Library" (below)
Usage Example A Folder that contains:
BleuRoseErrorLib An Alias for the real library (above)
Calling The Library.mcp CodeWarrior/PRO v5.3 project file
main.c Sample application source code
main.rsrc Sample application resources
Licensing the Error Library
The Bleu Rose Error Library requires a license (and a key) to be fully functional. The unlicensed library contains all of the available error codes. However, until the library is licensed, the contents of the STR 29271 resource will be substituted for Apple's explanation until a valid license key is added to the library. As delivered, that substitute string reads: "of an undescribed problem".
The terms of the license are as follows:
1) You agree to provide Bleu Rose Limited 2 fully licensed and functional copies of any software that incorporates BleuRoseErrorLib.
2) You agree to provide Bleu Rose Limited 2 fully functional sets of any hardware that accompanies the software described by item 1 above. If your software requires no hardware (other than a standard Macintosh), you are not required to provide any hardware.
3) You agree to disclose to Bleu Rose Limited the expected completion date and version number of the software described by item 1 above. This information will be restricted to those parties who signed the licensing agreement.
4) You agree to update our copies of your software at no charge to us as you release new versions of any software incorporating our error library.
5) You agree to let us use your company and/or product name in our own advertising without restriction upon formal release of your product.
To license the library, fill out the form found in the file titled "BleuRoseErrorLib License". Send 2 signed copies to us at:
Bleu Rose Ltd.
attn: Licensing
P. O. Box 5536
Hacienda Heights, CA 91745-0536
USA
We will send one copy back to you with our part signed as well. We will also include your license key with the signed document.
When you receive your license key, open the file BleuRoseErrorLib with a resource editor. Replace the contents of the 'LKey' resource with the key you received. The key will be 24 characters long. 'LKey' is defined as a Pascal string. Thus, the actual size of the resource will be 25 bytes. Verify this size after you replace the default key with your own. If the size of the resource isn't exactly 25 bytes, the software will return the kWarningLibraryNotLicensed error even though you have a valid license key.
Completing the Library
To keep the size of the electronic download reasonably small, we have included the error database in a single location ONLY (inside the Black & Bleu™ application itself). You will need to move that database into the BleuRoseErrorLib file before you use the library. An application called "Populate The Library" has been included in your package for this purpose. Run the application and follow the instructions it displays. This activity needs to be done only once.
Calling the Library
Apple, mostly through lack of organization, has come up with a rather incoherent collection of error numbers. Many are used over and over again with different meanings for each occurrence. For example, error 1 has more than 20 distinct meanings ranging from the traditional "Bus Error" to the rather obscure Apple Realtime Operating System Environment (AROSE) "Die Abort" error.
The Bleu Rose Library deals with this situation by placing each instance of the error on a separate list. When you ask for the error description, the lists will be searched until the error is found. While the software attempts to search the lists using a "most common to least common" algorithm, your definition of "most common" may differ from the one we used.
You can alter this search behavior by specifying the type of error you suspect the error to be. In that case, the search will continue until a match of the error type AND the error number occurs. If the search fails to match EITHER criteria, an error is returned. If the search finds the error but not the specified error type, a warning is returned along with the valid information for the error that WAS found.
A sample CodeWarrior Project is provided that illustrates how to call the library.
To use the library, your application must:
1) locate it
2) make it the current resource file
3) fill in the code resource's parameter block
4) extract the library's code resource
5) call the code resource
6) interpret the results
Sample code is provided (in source form) showing how to access the library and call it. Source for the library itself (the code resource) is not included.
There are 2 functions provided in source code form that show you how to perform the above steps.
FindBleuRoseErrorLibrary locates the library
CallBleuRoseErrorLibrary opens the library and looks up the error
The library itself has only 1 entry point. It requires a parameter block pointer that contains everything the library needs to return the desired data.
The parameter block is used as follows:
To obtain the description of an error given the error number, fill in the parameter block as follows:
Out-In Name Type Description
-> action SInt32 Set to kGetError
-> error SInt32 The error number to look up
-> proposedErrorTypeNumber SInt16 The Error Type value to try
<- actualErrorTypeNumber SInt16 The Error Type value matching the error found
<- errorTypeName Str255 Name string matching the Error Type number
<- pneumonic Str255 Apple's name for this error
<- description Str255 Apple's explanation of this error
The proposedErrorTypeNumber value is a number from 0 (k1stErrorTypeFound) through kZlastType-1. If you use a value of zero (k1stErrorTypeFound), the data returned will match the first occurrence of the error found in the database. This value SHOULD be the most common reason for the error. However, the definition of "most common" is subjective. It is based on the number of times that the error has been encountered at Bleu Rose Ltd. Obviously, we have not encountered all of the errors in actual code. Thus, without any data to go on, errors are ranked rather arbitrarily - typically in the order they were discovered.
To assist you in the ranking of an error, you can assign a ranking by using the proposedErrorTypeNumber field to specify a "guess" about the source of the error. For example, assume that you have received a -1 error value back from a function call. The "most common" meaning of this error is a "General System" error. And if you specified k1stErrorTypeFound in the proposedErrorTypeNumber field, you would get back a description of that error type. But in this case, say you were calling a printing function. Thus, it would be likely that the error value returned would be related to printing. To get a description that is more likely to fit your circumstance, you would fill in the proposedErrorTypeNumber field with kPrintingType. The description returned would then be correct for a printing error.
In the event that you guessed wrong and the error was NOT associated with printing, you would get back the "most common" description along with a warning status of kErrorTypeNotOnFile.
In every case, the actual error type found will be returned in the actualErrorTypeNumber field. The errorTypeName field will also contain the string matching the value returned in the actualErrorTypeNumber field.
If the error number can't be found at all, an error status of kErrorNotOnFile will be returned and the rest of the variables in the parameter block will be set to 0 or left empty.
To obtain the description of an error type given the error type number, fill in the parameter block as follows:
Out-In Name Type Description
-> action SInt32 Set to kGetType
-> error SInt32 (Not Used)
-> proposedErrorTypeNumber SInt16 The Error Type value to try
<- actualErrorTypeNumber SInt16 (Not Used)
<- errorTypeName Str255 Name string matching the Error Type number
<- pneumonic Str255 (Not Used)
<- description Str255 (Not Used)
If the error type number is not on file, a status of kErrorTypeNotOnFile will be returned.
Incorporating the Library into Your Own Application
You may choose to include the library as part of your application rather than shipping it as a separate file. To do so, simply add the library to your project. The sample program included in this collection uses that technique.
WARNING: The resource IDs used in the library must NOT be changed. If you do, the library's code resource will not work. Be sure to take note of any "Duplicate Resource" warnings issued by the linker. If you receive any, change the IDs of YOUR resources to eliminate the duplicate resource problem.
Note: The library uses resource ID 29271 (defined as kBleuRoseErrorLibCommonResID) for ALL of its resource IDs.
You may leave the file "as is" and simply include it as a separate file in your product's collection of files. The sample code illustrates how to "find" the library both in the same folder that contains your application and the system Extensions folder. If you choose to place the file in some other location, you will need to alter the sample code accordingly.
Note: BleuRoseErrorLib is NOT a true shared library. The file type is 'rsrc' rather than 'shlb'. As such, placing the file into the Extensions folder offers no particular advantage to you or your customers until you include it in more than one of your applications. If you use BleuRoseErrorLib in more than 1 application, each can reference the same copy of the library.
The longest pneumonic is 65 bytes long. It is associated with error -26695. The longest description is 207 bytes long. It is associated with error -3172.
Customizing the Error Library
In many cases, Apple has not provided any explanation at all for an error. For those cases, the contents of the STR 29271 resource will be substituted for the missing explanation. As delivered, the string reads: "of an undescribed problem". You may change this string to anything else you want to use.
Note: Apple's explanations have been modified to complete the following sentence correctly:
"An error occurred because ".
User System Requirements
BleuRoseErrorLib is designed to operate correctly on a User's machine if the following is available:
- Mac OS 7.0 or later
- 600 kB RAM
- 300 kB of Disk Space
Developer System Requirements
BleuRoseErrorLib is designed to be used with:
CodeWarrior v5.3 or newer using the C or C++ compilers
Apple Universal Headers v3.2 or newer
and requires:
- 500 kB of Disk Space
- 600 kB of RAM
Variations of this environment will probably work but may require small changes in the source code and the creation of your own CodeWarrior project file to build the sample project.
The library does NO checking for these requirements. It is your responsibility to validate the environment before using BleuRoseErrorLib.
